Add PHPDoc documentation to Type, Scope, and Reflection interfaces #4866

ondrejmirtes · 2026-02-10T18:01:41Z

Summary

Add PHPDoc documentation to the Type interface: all 90+ methods documented with purpose, behavior, and usage guidance
Add PHPDoc documentation to the Scope interface and its parent interfaces (InternalScope, ClassMemberAccessAnswerer, NamespaceAnswerer)
Add PHPDoc documentation to all Reflection interfaces reachable from Type and Scope: ParametersAcceptor, PropertyReflection, MethodReflection, ClassConstantReflection, ExtendedMethodReflection, ExtendedPropertyReflection, FunctionReflection, etc.
Add PHPDoc documentation to CompoundType and AccessoryType interfaces explaining double-dispatch and intersection semantics
Add PHPDoc documentation to supporting types: TrinaryLogic, AcceptsResult, IsSuperTypeOfResult, VerbosityLevel, GeneralizePrecision, TemplateTypeMap, TemplateTypeVariance, etc.
Remove obvious PHPDoc descriptions that are redundant with method names, tags, or common knowledge
Add PHPDoc writing guidelines and Type interface method addition pattern to CLAUDE.md

Test plan

Verify no functional code changes — only PHPDoc comments and CLAUDE.md
Run make tests to ensure nothing is broken

🤖 Generated with Claude Code

ondrejmirtes · 2026-02-11T07:27:45Z

src/Php/PhpVersion.php

+ * Represents a specific PHP version for version-dependent analysis behavior.
+ *
+ * The version is stored as PHP_VERSION_ID format (e.g. 80100 for PHP 8.1.0).
+ * Extension developers can access it via `Scope::getPhpVersion()` (which returns


Do not mention Scope here, only constructor injection.

ondrejmirtes · 2026-02-11T07:29:18Z

src/Reflection/Callables/CallableParametersAcceptor.php

-	 * value is unused at runtime a warning is emitted, PHPStan will emit the
-	 * warning during analysis and on older PHP versions too
+	 * On PHP 8.5+ if the return value is unused at runtime, a warning is emitted.
+	 * PHPStan reports this during analysis regardless of PHP version.


Keep the mention of NoDiscard attribute.

ondrejmirtes · 2026-02-11T07:32:56Z

src/Reflection/ParametersAcceptor.php

+ * Describes one signature variant of a function or method.
+ *
+ * A function/method may have multiple ParametersAcceptor variants — for example,
+ * the built-in `array_map` function has different signatures depending on argument count.


Use different example, like strtok or PDO::query().

ondrejmirtes · 2026-02-11T07:34:44Z

src/Reflection/PropertyReflection.php


+	/**
+	 * Returns false for typed properties (which always retain their declared type)
+	 * and true for untyped properties (which take on the type of whatever is assigned).


This does not seem precise. Research this more. I think the main difference is properties with different read/write types like @Property but take me up on that claim.

ondrejmirtes · 2026-02-11T07:35:50Z

src/Reflection/Type/UnresolvedMethodPrototypeReflection.php

+ *
+ * When calling a method on a generic type, the method's parameter and return types
+ * need to be transformed by substituting template type parameters with their concrete
+ * arguments. This interface allows that resolution to be deferred and configured:


This exists mostly because of StaticType.

One main implementation is used by ObjectType, the other by StaticType. Research which is which and update the comments.

ondrejmirtes · 2026-02-11T07:36:25Z

src/Reflection/Type/UnresolvedPropertyPrototypeReflection.php

+ *
+ * This is the return type of Type::getUnresolvedPropertyPrototype(),
+ * Type::getUnresolvedInstancePropertyPrototype(), and
+ * Type::getUnresolvedStaticPropertyPrototype().


This exists mostly because of StaticType.

One main implementation is used by ObjectType, the other by StaticType. Research which is which and update the comments.

ondrejmirtes · 2026-02-11T07:38:49Z

src/Type/Type.php

 	public function getMethod(string $methodName, ClassMemberAccessAnswerer $scope): ExtendedMethodReflection;

+	/**
+	 * Unlike getMethod(), this defers template type resolution.


ondrejmirtes · 2026-02-11T07:40:08Z

src/Type/Type.php

-	 * Returns a new instance with all inner types mapped through $cb. Might
-	 * return the same instance if inner types did not change.
+	 * Returns a new instance with all inner types mapped through $cb.
+	 * Returns the same instance if inner types did not change.


Not used directly but through TypeTraverser

ondrejmirtes · 2026-02-11T07:40:25Z

src/Type/Type.php


 	/**
-	 * Traverses inner types while keeping the same context in another type.
+	 * Like traverse(), but walks two types simultaneously.


Not use directly but through SimultaneousTypeTraverser

ondrejmirtes · 2026-02-11T07:41:48Z

src/Type/VerbosityLevel.php

+ *
+ *     $type->describe(VerbosityLevel::typeOnly())  // "string"
+ *     $type->describe(VerbosityLevel::value())      // "'hello'"
+ *     $type->describe(VerbosityLevel::precise())    // "non-empty-lowercase-string"


The precise level description is not the best and could be improvee. Research what types have different value vs precise description and update accordingly.

Document every method on the Type interface with descriptions of purpose, behavior, parameters, return values, and usage guidance. Key additions: - Interface-level doc explaining the central role of Type and the critical rule to never use instanceof for type checks - Core methods: isSuperTypeOf, accepts, equals, describe with examples - Class identification: getReferencedClasses vs getObjectClassNames vs getObjectClassReflections, getClassStringObjectType - Member access: canAccessProperties/canCallMethods/canAccessConstants and has*/get*/getUnresolved* patterns - Array operations: all 13 array transformation methods (chunk, flip, pop, shift, slice, splice, reverse, search, shuffle, etc.) - Offset access: isOffsetAccessible vs isOffsetAccessLegal, setOffsetValueType vs setExistingOffsetValueType - Type checking: all is* methods for scalars, strings, and arrays - Type conversion: all to* methods (toBoolean through toCoercedArgumentType) - Comparison: looseCompare, isSmallerThan, getSmallerType family - Templates: inferTemplateTypes, getReferencedTemplateTypes, traverse - Other: generalize, tryRemove, getFiniteTypes, hasTemplateOrLateResolvableType https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

Document every method on the Scope interface, ClassMemberAccessAnswerer interface, and NamespaceAnswerer interface with descriptions of purpose, behavior, parameters, return values, and usage guidance. Scope interface: - Interface-level doc explaining Scope as the analysis state at an AST position, listing all extension types that receive it as a parameter - File/context methods: getFile vs getFileDescription (trait handling), isDeclareStrictTypes, isInTrait/getTraitReflection - Function context: getFunction, getFunctionName, getParentScope - Variable tracking: hasVariableType, getVariableType, canAnyVariableExist (extract() handling), getDefinedVariables vs getMaybeDefinedVariables - Type resolution: getType (the core method), getNativeType (PHPDoc-free), getKeepVoidType (preserves void), getScopeType vs getType (deferred evaluation), getScopeNativeType - Name resolution: resolveName (self/static/parent handling), resolveTypeByName (preserves LSB via StaticType/ThisType) - Reflection helpers: getInstancePropertyReflection, getStaticPropertyReflection, getMethodReflection, getConstantReflection - Scope filtering: filterByTruthyValue/filterByFalseyValue for type narrowing in conditional branches - Context queries: isInClassExists, isInFunctionExists, isInClosureBind, isInAnonymousFunction, isInExpressionAssign, isUndefinedExpressionAllowed, isInFirstLevelStatement, getFunctionCallStack ClassMemberAccessAnswerer interface: - Interface-level doc explaining its role as visibility checker passed to Type methods for enforcing public/protected/private access - canReadProperty vs canWriteProperty (PHP 8.4 asymmetric visibility) - canCallMethod, canAccessConstant NamespaceAnswerer interface: - Interface-level doc explaining namespace resolution context https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

…pe and Scope interfaces Document all interfaces and classes reachable through parameter types and return types of the previously documented Type and Scope interfaces. This covers 31 files across the type system, reflection layer, and supporting infrastructure: - Core result types: TrinaryLogic, AcceptsResult, IsSuperTypeOfResult - Type system: VerbosityLevel, GeneralizePrecision, ConstantScalarType, TypeWithClassName - Reflection: ClassMemberReflection, PropertyReflection, ExtendedPropertyReflection, MethodReflection, ExtendedMethodReflection, FunctionReflection, ParameterReflection, ClassConstantReflection, ConstantReflection, ParametersAcceptor, ExtendedParametersAcceptor, PassedByReference, Assertions, AttributeReflection - Callables: CallableParametersAcceptor, SimpleThrowPoint, SimpleImpurePoint - Generics: TemplateTypeMap, TemplateTypeReference, TemplateTypeVariance - Prototype resolution: UnresolvedPropertyPrototypeReflection, UnresolvedMethodPrototypeReflection - PHP version: PhpVersion, PhpVersions https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

Based on git blame analysis of Type.php, document the recurring pattern of adding new methods to the Type interface as a bug fix strategy instead of scattering instanceof checks or utility calls across the codebase. https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

…ype interfaces CompoundType: Document the double-dispatch protocol for bidirectional type comparison, explaining why instanceof CompoundType is the correct pattern (unlike instanceof SomeSpecificType which is discouraged). Document all four methods with their decomposition semantics. AccessoryType: Document the marker interface's role as a refinement type that always lives inside an IntersectionType alongside a base type. Include a complete mapping table of all 13 implementations to their corresponding query methods on the Type interface. https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

…es, tags, or common knowledge https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

- PhpVersion: mention only constructor injection, not Scope - CallableParametersAcceptor: restore #[\NoDiscard] attribute mention - ParametersAcceptor: use strtok as multi-variant example - PropertyReflection: fix canChangeTypeAfterAssignment() description to explain it's about matching read/write types and property hooks - UnresolvedMethodPrototypeReflection: document ObjectType vs StaticType implementations (CalledOnType vs Callback) - UnresolvedPropertyPrototypeReflection: same as above - Type::getUnresolvedMethodPrototype(): add "and static type" to doc - Type::traverse(): note to use TypeTraverser::map() instead - Type::traverseSimultaneously(): note to use SimultaneousTypeTraverser - VerbosityLevel: improve precise level description with concrete examples Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

staabm · 2026-02-11T08:58:19Z

perfect AI use-case. awesome.

ondrejmirtes commented Feb 11, 2026

View reviewed changes

claude and others added 8 commits February 11, 2026 09:40

Remove obvious PHPDoc descriptions that are redundant with method nam…

4629288

…es, tags, or common knowledge https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

Add PHPDoc writing guidelines to CLAUDE.md

b67159a

https://claude.ai/code/session_01Htkqstd1mz1dbevHT6Y437

ondrejmirtes changed the title ~~Add comprehensive PHPDoc documentation to Type interface~~ Add PHPDoc documentation to Type, Scope, and Reflection interfaces Feb 11, 2026

Fix CS

d272471

ondrejmirtes force-pushed the claude/document-type-interface-qtagP branch from 5d9925c to d272471 Compare February 11, 2026 08:51

ondrejmirtes merged commit 3a06311 into 2.1.x Feb 11, 2026
74 checks passed

ondrejmirtes deleted the claude/document-type-interface-qtagP branch February 11, 2026 08:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add PHPDoc documentation to Type, Scope, and Reflection interfaces #4866

Add PHPDoc documentation to Type, Scope, and Reflection interfaces #4866

Uh oh!

ondrejmirtes commented Feb 10, 2026 •

edited

Loading

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

ondrejmirtes Feb 11, 2026

Uh oh!

Uh oh!

staabm commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add PHPDoc documentation to Type, Scope, and Reflection interfaces #4866

Add PHPDoc documentation to Type, Scope, and Reflection interfaces #4866

Uh oh!

Conversation

ondrejmirtes commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

staabm commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ondrejmirtes commented Feb 10, 2026 •

edited

Loading